Integration Guide Kassow Robots LS

Note: We strongly recommend that you read the Robot communication overview before this integration guide.

Note 2: We strongly recommend that you use the latest version of the integration guide. It is included in the latest version of the Robot module. To download the Robot module, visit the official Photoneo website.

Contents

1 Prerequisites

The Photoneo Locator Studio (LS) module for Kassow Robots is a Capability Bundle (CBun). A CBun is a binary extension that you install on the robot controller. It adds the Locator Studio commands directly to the program editor on the teach pendant. This CBun is built for the FireFly controller software (packages FireFly.5 to FireFly.7.x).

Note: Controllers with HagenHevany (software package 8.x) need a separate CBun build. This guide does not cover HagenHevany.

You need:

A Kassow Robots 7-axis robot with a Kassow Robots controller
Controller software package FireFly.5 to FireFly.7.x
A free Ethernet interface on the robot controller for the connection to the Photoneo vision controller
A USB stick (or network share) to transfer the .cbun file and the example programs to the controller
A Photoneo vision controller with a Locator Studio server that supports the 1.5.0 communication protocol

To check the installed software package, go to Menu -> Settings -> About on the teach pendant:

Note: In the handshake, the CBun identifies itself to the Locator Studio server as KASSOW_ROBOTS/L/1.5.0XXX. The vision controller selects the matching protocol features based on this string. For this reason, you need a Locator Studio server that supports the 1.5.0 protocol.

For general information on CBuns (how to manage them from the teach pendant, the basic interfaces and the control items), see the Kassow Robots Software Manual.

The Robot module consists of one CBun installer:

- photoneo_locator_studio.cbun

The package also contains a set of example programs in the folder Example Programs:
- LS_Main_Basic.kr2
- LS_Main_Basic_Hand_Eye.kr2
- LS_Main_Basic_Single_Object.kr2
- LS_Main_Basic_Multi_VS.kr2
- LS_Main_Basic_Change_Sol.kr2
- LS_Main_Basic_Change_BBox.kr2
- LS_Main_Basic_Comm_Check.kr2
- LS_Main_Basic_Multiview_Static.kr2
- LS_Main_Basic_Multiview_Dynamic.kr2
- LS_Main_Basic_Reuse_Scan.kr2
- LS_Calibration.kr2
- LS_Calibration_Hand_Eye.kr2

2 Robot controller setup

2.1 Network configuration

The Locator Studio CBun opens a TCP client connection from the robot controller to the Action Request Server on the Photoneo vision controller (default port 11003). For this reason, both devices must be reachable on the same subnet.

This guide uses these addresses:

Vision controller IPv4 address: 192.168.1.1 / 24
Robot controller IPv4 address: 192.168.1.2 / 24

Configure the Ethernet interface of the robot controller in the Settings menu of the teach pendant. See the Kassow Robots Software Manual for the exact procedure for your software version. Then set the matching addresses on the Network page of the Photoneo vision controller:

NOTE: The subnet mask 255.255.255.0 is the same as a 24-bit subnet mask. See this table for more combinations.

To ping the Kassow robot controller from the Photoneo vision controller, use the Test Connection button on the Network page of the vision controller:

2.2 Copying the CBun and example programs to the controller

Use a USB stick to transfer the Robot module files to the robot controller. Copy the delivered folder structure to the root of the stick and insert the stick into the USB port of the teach pendant. The file browsers used later in this guide expect this layout:

usb0 → Kassow → LS → CBun → photoneo_locator_studio.cbun
usb0 → Kassow → LS → Example Programs → *.kr2

Note: Install the CBun file only once per controller. Load the example programs one by one from the Program -> Open dialog. After the first save, the controller keeps them in its program storage.

2.3 Installing the Photoneo Locator Studio CBun

Open the main menu with the three-dot icon in the upper right corner of the teach pendant and select Settings -> CBuns:

The CBuns page lists all Capability Bundles installed on the controller. Use the plus (‘+’) button in the upper left corner to install a new one. The minus (‘-’) button uninstalls the CBun selected in the list.

Go to the CBun folder on the USB stick and select photoneo_locator_studio:

The installation dialog shows the bundle metadata. Check that the author is Kassow Robots and that the version is 1.5.0, then click Install:

After the installation, the Photoneo Locator Studio bundle appears in the list on the left. Select it to see the bundle details and the device classes it provides. Here, it provides one class named Locator Studio. Use the plus (‘+’) button on the right of the Locator Studio row to add a Locator Studio device to the workcell:

2.4 Configuring and activating the Locator Studio device

When you add the device, its configuration page opens. The NAME field contains the instance name. The program tree shows this name (default LOCSTU) as the prefix of every Locator Studio command. On the CONFIG tab, enter the connection parameters:

LOCATOR STUDIO IP ADDRESS - the IPv4 address of the Photoneo vision controller (192.168.1.1 in this guide)
PORT - the Action Request Server port, 11003 by default

Press Activate to open the connection. When the device is active, the warning triangle next to the CONFIG tab changes to a green check mark, and the Deactivate button becomes available:

Note: The device configuration is part of the workcell, not of the program. Save the workcell (Menu -> Workcell -> Save) after you add or change the Locator Studio device.

2.5 Tool (TCP) and payload setup

The tool setup is more important for Locator Studio than for Bin Picking Studio. Bin Picking Studio works with a zeroed tool and compensates for the offset in software. The general rule for Locator Studio is: do all scanning and calibration with a zero tool frame, and do all picking with the real tool. In this tutorial, the example programs use a TCP pose variable named tcp_init with a Z offset of 300 mm. Before you run the robot programs, set tcp_init to match the physical gripper. It is best to do this before you touch up the robot poses.

The example programs set the tool and the payload in the first two instructions of Sequence 1:

SET TCP = tcp_init
SET LOAD2 = load_init

Select the tcp_init variable in the variable bar at the bottom of the screen to edit the tool frame:

Do the same for load_init to enter the mass, center of gravity and inertia of the gripper:

Note: pho_calib_add always reads the current flange-center pose (flange to world), so it does not depend on the configured TCP. Hand-eye scan requests work the same way. You do not need to switch tools around the vision requests, but the picking motions must use the real tool frame.

3 Robot module

Note: We strongly recommend that you read the Photoneo robotic API before this section.

3.1 Connection to the Photoneo vision controller

The CBun opens the connection to the Action Request Server on the vision controller when the Locator Studio device is activated. You can activate it manually on the device CONFIG page (section 2.4), or it activates automatically when the workcell is loaded. Set the LOCATOR STUDIO IP ADDRESS field to the IP address of your vision controller. In this tutorial, it is 192.168.1.1.

The robot can send requests to the vision controller only after the connection is open. The green CONNECTED indicator on the Deployment page of Locator Studio shows a successful connection:

On the robot side, the green check mark on the CONFIG tab of the Locator Studio device shows the connection state. You can also check the link from the program at any time with the pho_req_comm_check command. It returns response code 0 when the connection is alive - see the LS_Main_Basic_Comm_Check example program.

3.2 Request list

This section describes the API calls of the Robot module. Insert these commands into the program tree from the CBuns tab of the command palette. They are for high-level control of the locator application.

Note: See Action requests for details of the communication protocol.

Note: The ID column lists the request code sent over the Photoneo communication protocol. pho_calc_approach_pose is only a local geometry helper. It sends no request to the vision system.

Request	ID	CBun command	Input	Populates
Calibration Start	25	`pho_calib_start`	Solution Id Vision System Id	Response Code
Calibration Add Point	5	`pho_calib_add`	None (the current flange pose is read automatically)	Response Code
Calibration Save	27	`pho_calib_save`	None	Calibration Accuracy [µm] Calibration Matrix (RobotPose) Response Code
Calibration Stop	26	`pho_calib_stop`	None	Response Code
Scan (blocking)	19	`pho_req_scan_full`	Vision System Id Scan Type (Extrinsic / Hand-eye)	Response Code
Scan Start (non-blocking)	19	`pho_req_scan`	Vision System Id Scan Type (Extrinsic / Hand-eye)	—
Wait for Scan	19	`pho_wait_scan`	None	Response Code
Trigger Scan (MultiView)	30	`pho_req_capture`	Vision System Id Scan Type (Extrinsic / Hand-eye)	Response Code
Reuse Scan	31	`pho_req_reuse_scan`	Vision System Id Scan Type (Extrinsic / Hand-eye)	Response Code
Get Single Object	20	`pho_req_get_single_object`	Vision System Id Pose Mask	Detected Object Pose Response Code Solution-based Info data: Tool Invariance, Gripping Point Id, Gripping Point Invariance, Object Dimension X / Y, Object Rotation Z, NN Label, Max Z Height, Tilt
Get Objects	20	`pho_req_get_objects`	Vision System Id Requested Object Count (0 = all)	Object Poses Array Returned Object Count Response Code
Get Vision System Status	22	`pho_req_get_status`	Vision System Id	Localized Object Count Number Of Ready Processing State Response Code
Change Solution	9	`pho_change_sol`	Solution Id	Response Code
Start Solution	10	`pho_req_start_sol`	Solution Id	Response Code
Stop Solution	11	`pho_req_stop_sol`	None	Response Code
Get Running Solution	12	`pho_req_get_run_sol`	None	Solution Id Response Code
Get Available Solutions	13	`pho_req_get_avail_sol`	None	Solution Id Array Response Code
Change Bounding Box	33	`pho_change_bbox`	Vision System Id Bounding Box Id	Response Code
Comm Check	100	`pho_req_comm_check`	None	Response Code
Calculate Approach Pose	local	`pho_calc_approach_pose`	Target Pose Reference Frame (World / Tool) Axis (X / Y / Z) Offset [mm]	Approach Pose Response Code

Note: pho_req_scan_full does the scan and waits for the result in one step. pho_req_scan and pho_wait_scan split the same request into a non-blocking start and a blocking result read. With a hand-eye sensor, keep the robot still until the scan response arrives. With an extrinsic sensor, the robot can move in the meantime if it stays out of the scanned scene. All three use request code 19.

Note: Only pho_req_get_single_object returns per-object Info data, as optional scalar Number output parameters. Bind only the fields that you need. Fields that the active solution type does not fill are returned as 0. Units are listed in section 3.5.

Every request also has an optional Response Code output. If you bind it to a program variable, the error pop-up window does not appear, and the program handles the error. See section 4.2 for how to bind it. See Error codes for the error codes, their description and troubleshooting.

3.3 Value functions

In addition to the program commands above, the CBun provides value functions. You can use them directly in expressions, for example in an IF or LOOP condition. You do not need a separate program step:

Function	Input	Returns
`pho_fce_get_object`	Vision System Id, Pose Mask	RobotPose - next localized object pose
`pho_fce_get_num_ready`	Vision System Id	Number - number of localized objects waiting for processing
`pho_fce_get_loc_count`	Vision System Id	Number - total number of detected objects, including rejected ones
`pho_fce_get_proc_state`	Vision System Id	Number - 0 when processing is complete, 1 while recognition is running
`pho_fce_get_run_sol`	None	Number - ID of the currently deployed solution

3.4 Example programs

The Photoneo Kassow module includes several example programs. They show how to use the requests listed in section 3.2 for different use cases:

Example program	Description
LS_Main_Basic LS_Main_Basic_Hand_Eye	These simple examples show the basic workflow for statically mounted and hand-eye sensors: connect to a vision controller, send a scan request, request and receive object poses, and execute the picks. The scan is split into `pho_req_scan` and `pho_wait_scan`. One `pho_req_get_objects` call gets the poses into `object_pose_array`. The program then loops over `num_of_recv_objects` picks. `pho_calc_approach_pose` calculates the approach pose locally. The examples also show error handling. Each command writes its result into the `status` variable.
LS_Main_Basic_Single_Object	Same as LS_Main_Basic, but it gets one object at a time with `pho_req_get_single_object`. This command also returns the per-object Info data (object dimensions, rotation, NN label, tilt, gripping point ID, …) as optional scalar output parameters.
LS_Calibration LS_Calibration_Hand_Eye	Calibration examples for statically mounted and hand-eye sensors. Requirements: you must start and confirm the first calibration of the vision system manually in Locator Studio. Calibration steps: teach all 9 calibration poses (P1 - P9). To add points to the calibration table, click “Add Calibration Point” in Locator Studio, or call `pho_calib_add` directly from the program. Calibration accuracy: as a general rule, the calibration error must stay below 3 mm. Higher errors usually mean a systematic problem in the calibration setup. Automatic recalibration (optional): after the first calibration is successful, enable automatic recalibration in the vision system settings. Then use `pho_calib_start`, `pho_calib_add`, `pho_calib_save` and `pho_calib_stop` to run the recalibration cycle. Important: the calibration object must stay where it was during the first calibration. The calibration ball stays mounted in the same place on the flange or gripper and moves with the robot. The marker pattern stays in the same place in the cell. Otherwise, the automatic recalibration fails.
LS_Main_Basic_Multi_VS	Same as LS_Main_Basic, but it switches between two vision systems. The Vision System Id parameter of every request is essential in this setup. It selects the vision system to trigger or query.
LS_Main_Basic_Change_Sol	Same as LS_Main_Basic, but with all requests for solution switching. It shows how to activate different solutions with `pho_req_start_sol`, `pho_req_stop_sol` and `pho_change_sol`. The Solution Id parameter selects the solution to switch to. The solution switching logic is at the top and at the bottom of the main loop.
LS_Main_Basic_Change_BBox	Same as LS_Main_Basic, but it switches the active localization bounding box at runtime with `pho_change_bbox`. The robot program can switch between preconfigured scan volumes during operation, without a change of the solution in Locator Studio.
LS_Main_Basic_Comm_Check	Same as LS_Main_Basic, but the program checks the link to the vision controller with `pho_req_comm_check` before it enters the main loop. If the returned status is non-zero, the program shows a dialog and stops. Use this check at program start or after a reconnection.
LS_Main_Basic_Multiview_Static	Static MultiView (meshing) example. It shows how to stitch several scans before the localization starts. This is useful for complex scenes or large objects. It uses a static approach: the robot stops at each scanning position to trigger and capture a scan. Procedure: move through all scanning poses (`scan_pose_1` - `scan_pose_3`) and call `pho_req_capture` in each of them. When the capture sequence is complete, start the localization with a regular `pho_req_scan`. This request does not do a real scan and emits no light. It only starts the localization on the collected data. Scan limit: keep the total number of scans below 10 for the best system performance.
LS_Main_Basic_Multiview_Dynamic	Dynamic MultiView example. It shows the integration of the Photoneo Instant Meshing technology. It uses the MotionCam-3D Parallel Structured Light technology to capture several scans while the robot moves. This quickly collects the 3D data into one point cloud. The program uses a second program sequence (Sequence 2) that runs in parallel with the motion sequence. The motion sequence sets the `meshing_on` flag before the scanning trajectory starts and clears it at the end. The scanning sequence loops on that flag and sends `pho_req_capture` at the configured interval. Requirements: Instant Meshing needs a MotionCam-3D (standard PhoXi 3D Scanners do not support dynamic scanning). In the LS solution, set `pho_mesh_dynamic` to True. The recommended value of `pho_capture_gap` is approximately 500 ms. Trajectory control: keep the scanning trajectory smooth and keep the bin in the field of view of the scanner, so that tracking is not lost.
LS_Main_Basic_Reuse_Scan	Same as the LS_Main_Basic_Multi_VS example, but it adds `pho_req_reuse_scan`. This request is useful when the scene has not changed since the last scan, but the localization must run again with a different configuration. For example, it searches for different objects or uses different bounding boxes or different settings. Procedure: do a regular scan for VS1 to capture the scene. Then use `pho_req_reuse_scan` for VS2 to reuse the scan data from VS1. This repeats the localization with a different configuration without new image data.

3.5 Info data

Some responses carry additional values - the Info data. The CBun has no registers. It passes the Info data to the program as optional outputs of the CBun commands. Bind a Number variable to the outputs that you need. The values keep the unit in which they were sent. Keys that the active solution does not send are returned as 0.

Key	Name	Where to read it in the robot program	Unit in robot
1	Tool point invariance	`Tool Invariance` output of `pho_req_get_single_object`	index
2	Gripping point ID	`Gripping Point Id` output of `pho_req_get_single_object`	index
3	Gripping point invariance	`Gripping Point Invariance` output of `pho_req_get_single_object`	index
4	Dimension X	`Object Dimension X` output of `pho_req_get_single_object`	mm
5	Dimension Y	`Object Dimension Y` output of `pho_req_get_single_object`	mm
6	Rotation Z	`Object Rotation Z` output of `pho_req_get_single_object`	mrad
7	Neural network label	`NN Label` output of `pho_req_get_single_object`	integer
8	Max Z height	`Max Z Height` output of `pho_req_get_single_object`	mm
9	Tilt	`Tilt` output of `pho_req_get_single_object`	mrad
10	Calibration accuracy	`Calibration Accuracy` output of `pho_calib_save`	µm
11	Running solution ID	`Solution Id` output of `pho_req_get_run_sol`; `pho_fce_get_run_sol`	integer
12	Number of localized objects	`Localized Object Count` output of `pho_req_get_status`; `pho_fce_get_loc_count`	integer
13	Number of ready objects	`Number Of Ready` output of `pho_req_get_status`; `pho_fce_get_num_ready`	integer
14	Processing state	`Processing State` output of `pho_req_get_status`; `pho_fce_get_proc_state`	0 / 1

Note: pho_req_get_objects returns only object poses. To read keys 1-9 of an object, get it with pho_req_get_single_object.

3.6 Error codes

The CBun passes the error codes from the vision controller to the program without change. The table below lists the codes that a Locator Studio solution can return. See Error codes for the description and troubleshooting of each code.

Code	Name
0	No error
1	Service error
2	Unknown request
3	Communication error
4	Bad data
5	Timeout
7	Brand does not match
8	Bin picking in simulation mode
100-134	Calibration point errors
255	Wrong bin picking configuration
450	Invalid solution ID
451	Another solution running
452	Deployment not started
453	Deployment is not running
454	Deployment did not stop
455	Solution is not complete
457	Invalid robot brand
458	Solution already running
459	Solution access unauthorized
460-469	Automatic calibration errors (460 invalid vision system, 461 calibration already running, 462 calibration not running, 463 calibration stop error, 464 calibration start error, 465 calibration disabled, 466 not enough calibration points, 467 calibration accuracy above the allowed threshold, 468 scanner not available, 469 calibration forbidden)
471	No valid license
500	Vision system not found
501	Empty scene
502	No object found, Detection running
503	No object found, Detection stopped
504	All objects rejected, Detection running
505	All objects rejected, Detection stopped
506	Robot-mounted scanner requires scan pose
507	Cell-mounted scanner forbids scan pose
508	Invalid scanner mount parameter
509	Request forbidden
510	Unknown error
511	Bounding box not found

The CBun itself also returns these codes:

Code	Meaning
2	`pho_calib_start`, `pho_change_sol`, `pho_req_start_sol`, `pho_change_bbox`: an ID parameter is negative or not a whole number.
-1	Communication error: the CBun could not open the connection or send the request, or no response arrived before the timeout (see section 5). `pho_calc_approach_pose`: invalid Reference Frame or Axis.
-5	Unexpected response: the response contained neither data nor an error code.

4 Runtime

When the solution is fully configured on the vision controller, finish the remaining steps on the robot side and run the LS_Main_Basic program.

4.1 Loading an example program

Open the main menu and select Program -> Open. Go to the Example Programs folder on the USB stick and select the program that you want to run:

Click Open to confirm the dialog. Opening a program replaces the active program, so save your work first if needed:

4.2 Program structure

All main example programs have the same structure. Using LS_Main_Basic as the reference:

SET TCP = tcp_init and SET LOAD2 = load_init - set the tool frame and the payload (see section 2.5)
MOVE J Start - move to the Start pose above the bin
LOOP - the endless pick and place loop
- Trigger Scan - LOCSTU pho_req_scan followed by LOCSTU pho_wait_scan
- Request Object Poses - LOCSTU pho_req_get_objects fills object_pose_array and num_of_recv_objects
- Pick all received objects - a FOR loop with num_of_recv_objects steps
  - Prepare poses - object_pose = object_pose_array[iter,0] and LOCSTU pho_calc_approach_pose
  - Approach Object - MOVE L approach_pose, MOVE L object_pose
  - Gripper Command - SET DO1 = 1, WAIT
  - Deapproach - MOVE L approach_pose
  - Placing - MOVE J place_up, MOVE L place_down, SET DO1 = 0, WAIT, MOVE L place_up

Select a LOCSTU line in the program tree to see and edit the request parameters in the Options panel on the right. The scan request takes the Vision System Id and the Scan Type (Extrinsic for statically mounted sensors, Hand-eye for sensors carried by the robot):

pho_req_get_objects gets several localized poses in one request. Requested Object Count is the maximum number of poses to get (2 in LS_Main_Basic, 5 in LS_Main_Basic_Hand_Eye; 0 = all available objects, keep it at 100 or less). Bind Object Poses Array and Returned Object Count to the program variables that the picking loop uses:

Scroll down in the Options panel to bind the Response Code output parameter to the status variable. Every request has this optional output, and the program must check it:

pho_calc_approach_pose calculates the approach pose from the received object pose. With Reference Frame set to Tool and Axis set to Z, a positive Offset moves the approach pose back along the Z axis of the object, away from the object. The object orientation does not change:

4.3 Gripper commands

Locator Studio does not control gripper commands. Use regular SET DO or other I/O commands to control the gripper at the grasp and drop points. In the example programs, SET DO1 = 1 closes the gripper when the robot reaches the object pose, and SET DO1 = 0 opens it at the placing position. A WAIT instruction follows each of them:

4.4 Teaching the robot poses

After you open LS_Main_Basic or another template, touch up these poses before you run the program:

Start - usually above the center of the bin or of the scanning area, in a position where the robot is out of the field of view of the scanner.
place_up / place_down - the placing position. place_down is the drop point, and place_up is the retract pose above it.
scan_pose_1 … scan_pose_3 - the additional scanning waypoints of the MultiView examples.
Calib_Start, P1 … P9 - the calibration start pose and the nine calibration poses of the calibration programs.
P10 … P13 - the retract path of LS_Calibration (P13 → P10) after pho_calib_stop. Reteach or delete these moves for your cell.
home_pose - a pose variable in both calibration programs for your own start / end move. The shipped programs do not move to it.

The poses are program variables. The variable bar at the bottom of the screen lists them. Select a pose variable to open its editor:

To touch up a pose, jog the robot to the new position with the Jogging panel on the left, in Work Space or in Joint Space:

Then open the pose variable, press Define Pose and click Define to confirm. The dialog shows the pose calculated from the current TCP and joint configuration, transformed into the selected reference pose:

Note: Kassow robots have 7 joints, so a Cartesian pose does not define one unique arm posture. The joint configuration stored with the pose (J1 - J7) solves this redundancy. For this reason, always teach poses by jogging the real robot, not by typing coordinates.

Edit the motion parameters (trajectory type, blend point and speed) of every MOVE instruction in the same Options panel:

4.5 Calibration

Locator Studio has 3 calibration methods:

Sphere calibration - for statically mounted sensors
Marker pattern calibration - for sensors carried by the robot (hand-eye)
Marker pattern calibration - for static sensors and user / work object calibration

The first two methods need captures of a calibration object from 9 poses with enough variation in the tool pose data. Always calibrate with a zero tool frame and in the world frame. Non-zero frames can distort the calibration result.

For the third method, one scan is enough. The main difference from the first two methods is the origin of the scene. It is not the robot origin, but the origin of the marker pattern. You cannot automate the third method. You must do it manually.

You can also do the first two calibration procedures without the calibration programs of the Kassow module. Start the calibration in LS, jog the robot from point to point and add the points manually in LS. However, for production setups that need recalibration, we recommend that you record the calibration points in the program. Make sure that the motion between these poses is collision-free.

The Kassow module provides two programs for automatic calibration:

LS_Calibration - calibration procedure for a statically mounted sensor (sphere calibration).
LS_Calibration_Hand_Eye - the same procedure for a hand-eye sensor carried by the robot (marker pattern calibration).

Both programs move the robot through the taught poses P1 - P9 and call pho_calib_add in each pose. At the end, they call pho_calib_save and pho_calib_stop. In this way, they recalibrate automatically, without any action in LS. Before you run them, set the Solution Id and Vision System Id of pho_calib_start to your own solution. The shipped programs use Solution Id 33 (LS_Calibration) and 38 (LS_Calibration_Hand_Eye). pho_calib_save returns the Calibration Accuracy in µm (3 mm = 3000 µm).

In general, the calibration error must be below 3 mm. On the Verification tab, check that the point cloud matches the robot body and the gripper exactly. Investigate any difference, because it can cause a collision. The most common causes are wrong tool frame values, wrong gripper model orientation, wrong robot model, encoder zeroing and an unstable robot base.

4.6 Prerequisites

Do a final check before you run the Locator Studio application from the robot side. Make sure that:

the Locator Studio solution is correctly configured on the vision controller,
the network setup on the robot side is complete and the Locator Studio device is active,
all vision systems in the solution are calibrated,
the tool frame (tcp_init) and the payload (load_init) match the physical gripper,
all local poses in the main program are touched up correctly,
the gripper procedures are ready and work.

4.7 Running the LS_Main_Basic program

Deploy your solution on the vision controller. The Action Request Client status on the Deployment page changes to CONNECTED when you activate the Locator Studio device on the robot side:

NOTE: We strongly recommend that you set the Master Speed to a low value, for example 25%, before you run the program for the first time. The Master Speed slider is in the lower left corner of the teach pendant in Program Mode.

Switch to Program Mode and press Play. The first instruction is a motion command, so the controller asks for an interactive move to the Start pose. Press and hold the button until the robot reaches the target pose. Release it at any time to stop the movement:

When the robot reaches the Start pose, the program continues automatically. The sensor captures the first scan, and the localization starts to find objects. The program tree highlights the instruction that is running:

If there is a pickable object in the scene and the robot controller has received its Cartesian pose, the robot starts to move to the first object.

If everything looks correct, keep moving the robot to the first target and check that the path is correct. If the robot stops too far from the object or pushes it too deep, change the object origin or the tcp_init tool frame.

If the robot movement looks correct, set up your own placing routine and slowly increase the Master Speed back to 100%.

Congratulations, you have successfully deployed the Photoneo Locator Studio interface for Kassow Robots. You can now continue to improve your application. Use the Kassow LS 1.5.0 Quick Reference workbook (delivered with this guide) and the example programs as your guides.

5 Troubleshooting

Errors returned by the vision controller. If the Response Code of a command is bound to a program variable, the CBun writes the code there and the program continues. Check the code after every request. If the Response Code is unbound, a non-zero code stops the program, and the teach pendant shows the error description. See section 3.6.

Communication errors. If the connection is lost, a request cannot be sent or no response arrives in time, the command fails with code -1. The program then always stops, even if the Response Code is bound. The CBun waits for a response for:

30 s - pho_req_scan_full, pho_req_scan / pho_wait_scan, pho_calib_add, pho_req_get_single_object, pho_req_get_objects, pho_req_capture, pho_req_reuse_scan, pho_req_get_run_sol
20 s - pho_calib_start, pho_calib_save, pho_calib_stop, pho_change_sol, pho_req_start_sol, pho_req_stop_sol
3 s - pho_req_get_status, pho_req_get_avail_sol
5 s - all other requests

Reconnecting. The CBun opens the connection to the vision controller only when the Locator Studio device is activated. It does not reconnect automatically. After a restart of the vision controller or a network failure, deactivate and activate the device on the CONFIG tab (section 2.4). If the activation fails, check the IP address and port, and use the Test Connection button on the Network page of the vision controller.

The robot does not move to the object. Pose variables that the CBun writes at run time (object_pose, approach_pose, calib_matrix) must have scope shared. Always use MOVE L to reach a pose from the vision system. The CBun writes only the Cartesian part of the pose, so a MOVE J would go to the joint configuration that the variable was taught with.

6 Version and brand ID

Robot module version	1.5.0 (shown in the CBun installation dialog, section 2.3)
CBun file	`photoneo_locator_studio.cbun`
Controller software	FireFly.5 to FireFly.7.x
Brand ID	`KASSOW_ROBOTS/L/1.5.0XXX` (sent on the Action Request link, port 11003)

The LS module has no Robot State Server. See the Robot module support matrix for the supported Locator Studio versions.

7 Migration

For the general changes between LS 1.4 and LS 1.5, see Migration from LS 1.4.x to LS 1.5.x. Kassow-specific changes:

All commands and functions were renamed to the pho_* convention (for example scan → pho_req_scan_full, scanStart → pho_req_scan, scanGetResult → pho_wait_scan, getObject → pho_req_get_single_object, getObjects → pho_req_get_objects).
pho_req_get_single_object has new optional outputs for the Info data keys 1-9.
New commands: pho_req_capture, pho_req_reuse_scan, pho_change_bbox, pho_req_comm_check, pho_req_get_objects and the local helper pho_calc_approach_pose.
The brand ID changed to KASSOW_ROBOTS/L/1.5.0XXX. You need a Locator Studio that supports the 1.5 protocol.

You must create programs saved with an older CBun again with the new commands.